Release 10.1A: OpenEdge Development:
Web Services

SOAP—the message medium

As described in OpenEdge Getting Started: Application and Integration Services , SOAP is the protocol used to format message exchanges between Web service clients and Web services. The industry currently considers many scenarios for Web services communications (described at http://www.w3.org/TR/ws-arch-scenarios/). OpenEdge supports variations of the request-response scenario.

In the request-response scenario, a client (Web service client) sends a SOAP request message to invoke a Web service operation and the operation sends a response back to the client in the form of a SOAP response message (for a successful invocation) or in the form of a SOAP fault message (for an invocation that results in an error).

SOAP message document structure

SOAP messages have a common XML document structure that consists of the following ordered elements:

<?xml version="1.0" encoding="utf-8" ?> <soap:Envelope . . . >    <soap:Header>       .       .       .    </soap:Header>    <soap:Body       .       .       .    </soap:Body> </soap:Envelope>

These SOAP elements have the following functions:

Envelope (mandatory) — Defines all the namespaces used in the document. Namespaces are identifiers that provide a way to define XML elements without name conflicts. This is important for a Web service because it must be able to define its elements uniquely across the Internet, as well as to identify elements from other namespaces commonly used by all Web services on the Internet, such as the namespace for the SOAP specification itself. A namespace is typically defined by a Universal Resource Identifier (URI), usually in the form of a Universal Resource Locator (URL) or a Universal Resource Name (URN). The WSDL files that define Web service interfaces use namespaces in the same way (see the "WSDL—an overview" section).
Header (optional) — Used to send application-specific information, such as context and firewall information, including a standard set of attributes that describe the operation, and one or more entry elements that contain the specific information about the application. A good example of information passed in such a header entry is the object ID passed in the SOAP header for Progress 4GL Web services that maintain context for a session-managed AppServer (see Chapter 3 "Session Models and Object IDs in Progress 4GL Web Services").
Body (mandatory) — Contains data and SOAP formatting information according to the type of message it is. So, for a:
SOAP request message — The body contains the operation name and its input parameter values.
SOAP response message — The body contains any operation output parameters and any return value for a successful request.
SOAP fault message — The body contains error information for a failed request, including a set of standard attributes sufficient to identify the error and zero or more detail elements unique to the application that provide more complete information about what caused the error.

With some Web services, you do not have to have any direct knowledge of SOAP message structure to use them. These are Web services for which all the operation parameters map directly to 4GL data type parameters. For such Web services, especially where even SOAP faults can be ignored, you can interact with them in the 4GL without regard to SOAP message structure. The WSDL Analyzer also reduces your need to know SOAP in depth because it provides documentation on exactly what you need to do in the 4GL to use Web service operations. For an example of 4GL interaction with such a service, see the "Interacting with a Web service and its operations" section.

Many of the more complex Web services require direct 4GL interaction with the underlying XML in each SOAP message, in addition to any mapping of Web service parameters directly to 4GL data types. The Progress 4GL supports access to XML with an implementation of the Document Object Model (DOM) and Simple API for XML (SAX). For more information this XML support, see OpenEdge Development: Programming Interfaces . For more information on when and what you need to do to access the XML for SOAP request and response messages, see the "Handling Web service operation outputs and inputs" section.

Also, if you must handle the SOAP faults returned from a Web service request, you might need to access the underlying XML for the SOAP fault. For more information on when and what you need to do to access the underlying XML for a SOAP fault, see the "Handling Web service errors" section.

SOAP message formats

SOAP messages can be generated using several different formats, depending on the communications scenario. OpenEdge supports request-response scenarios that use the following SOAP formats:

RPC/Encoded
RPC/Literal
Document/Literal

To hide the details of these SOAP formats, OpenEdge provides the WSDL Analyzer. This utility reads a WSDL file and translates the Web service interface definition into a 4GL interface that you can use to access the Web service. Generally, when writing a Web service client in the 4GL, especially if you use the WSDL Analyzer (see the "OpenEdge WSDL Analyzer" section), you have no need to know the SOAP message format of the Web service you are using. However, if the Web service that you choose supports a different SOAP format than those supported by OpenEdge, the analyzer indicates that OpenEdge cannot support the Web service.

The WSDL Analyzer also recognizes and handles the Microsoft® wrapped document literal (Wrapped Doc/Lit) convention. Wrapped Doc/Lit is a convention using Document/Literal that wraps all request parameters for an operation into one input XML complex type and wraps all response parameters into a separate output XML complex type. By default, for each Web service operation, the Analyzer documents and the run-time 4GL handles these request and response parameters in unwrapped form, as individual input and output parameters. For more information, see Chapter 8, " Analyzing WSDL for Progress 4GL Access to Web Services."